<?
/*************************************************************************
<Header> 
 <Title>         C_colorcycle.inc          </Title>
..........................................................................
 <Description>
      This defines an object which provides automatically alternating
       colors with each successive call to the getColor() method. By
       default it returns white and light-green, good for alternating
       row color in an html report.
 </Description>
......................................................................
 <Author>Damien DeZurik</Author>
 <Date>2003-08-26</Date>
......................................................................
 <License version='open'>
      This code may be used in its current form or modified as much
       as desired by anyone responsible for anything using it.
 </License>
......................................................................
 <Notes>

 </Notes>
......................................................................
 <Usage>
	// -----------
	// Example 1 - Declere an instance with default white and light green color cycle.
	$obj_lineColor = new ColorCycle();
	
	// Now simply call the getColor() method to cycle through colors;

	while( $r = getDatabaseRows() ) {
		print "<tr bgcolor=\"" . $obj_lineColor->getColor() . "\"><td>$r[2]</td></tr>";
	}
	// -----------
	// Example 2 - Initialize with an array of custom colors.
	$cc = new ColorCycle(array("#FF0000","#FFFFFF","#0000FF"));

	// -----------
	// Example 3 - Sticky color changing only when stick field changes.
	$cc = new ColorCycle();
	while( $r = pg_fetch_array($pgo->res) ) {
		// getStickyColor will only return the next color in the cycle when
		//  $r[0] has changed to something new.
		$blockColor = $cc->getStickyColor($r[0]);

		// getStickyFieldIfChanged returns the value of the sticky field the first
		//  time it is called after the field has changed. If the value of the field
		//  has not changed since the last call, it returns a blank string. This gives
		//  the effect illistrated below where a column that repeats the same value
		//  ("department 20") does not repeat the same value row after row and, instead,
		//  only shows the value the first time it is encountered then blanks for successive
		//  rows until the value changes.  Used in combination with getStickyColor nicely
		//  colors all the rows with the same sticky field in the same color.  When the
		//  sticky field changes, so does the background color.  See example below.
		//  +---------------+------+
		//  | department 20 | $15k |  // background color is light green
		//  +---------------+------+
		//  |               |  $2k |  // background color is light green
		//  +---------------+------+
		//  | department 99 | $31k |  // background color is white
		//  +---------------+------+

		print "<span style=\"color:$blockColor;\">".print $cc->getStickyFieldIfChanged()."</span>";
		print "<span style=\"color:$blockColor;\">$r[1]</span>";
	}
 </Usage>
......................................................................
 <Changelog />
 </Changelog>
</Header>
********************************************************************/

Class ColorCycle {
	// Member variables.
	var $colorArrIndex;
	var $colors=array();
	var $stickyFlagLast;
	var $stickyFlagCurrent;
	var $stickyFlagChanged;

	var $LTGREEN="#EEFFEE";
	var $LTGREY="#EEEEEE";
	var $WHITE="#FFFFFF";

	// Cstr
	function ColorCycle($colorArr="")
	{
		if( empty($colorArr) )
			$colorArr = array($this->LTGREEN,$this->WHITE);

		// Start here because getColor() increments first.
		$this->colorArrIndex = -1;

		// Just set colors array to incoming array of colors
		$this->colors = $colorArr;

		// Keeps track of last flag value so getStickyColor($flag) knows
		//  when to change color.  Initialized to a string that is
		// Unlikely to be encountered.
		$this->stickyFlagLast = "|:|";

		// Current sticky field value
		$this->stickyFlagCurrent = "|:|";

		// So client knows when flag field has changed.
		$this->stickyFlagChanged = false;
	}

	// Member functions
	// set colors using array
	function setColors($colorArr)
	{
		$this->colors = $colorArr;
	}

	function getColor()
	{
		$this->colorArrIndex++;

		// Reset to 0 after arraysize exceeded.
		if( $this->colorArrIndex > (count($this->colors) - 1) )
			$this->colorArrIndex = 0;

		return $this->colors[$this->colorArrIndex];
	}

	// When called with a flag field, only alternates color when the field
	//  has changed.
	function getStickyColor($flag)
	{
		$this->stickyFlagCurrent = $flag;
		// If flag has changed, switch color
		if( $this->stickyFlagCurrent != $this->stickyFlagLast ) {
			$this->colorArrIndex++;
			$this->stickyFlagChanged = true;

			// Reset to 0 after arraysize exceeded.
			if( $this->colorArrIndex > (count($this->colors) - 1) )
				$this->colorArrIndex = 0;
		}
		else
			$this->stickyFlagChanged = false;

		$this->stickyFlagLast = $this->stickyFlagCurrent;

		return $this->colors[$this->colorArrIndex];
	}

	function getStickyFieldIfChanged()
	{
		if( $this->stickyFlagChanged )
			return $this->stickyFlagCurrent;
		else
			return "";
	}
}

?>
